Crate hb_subset

source ·
Expand description

This crate exposes HarfBuzz API for subsetting fonts.

What is subsetting?

From HarfBuzz documentation:

Subsetting reduces the codepoint coverage of font files and removes all data that is no longer needed. A subset input describes the desired subset. The input is provided along with a font to the subsetting operation. Output is a new font file containing only the data specified in the input.

Currently most outline and bitmap tables are supported: glyf, CFF, CFF2, sbix, COLR, and CBDT/CBLC. This also includes fonts with variable outlines via OpenType variations. Notably EBDT/EBLC and SVG are not supported. Layout subsetting is supported only for OpenType Layout tables (GSUB, GPOS, GDEF). Notably subsetting of graphite or AAT tables is not yet supported.

Fonts with graphite or AAT tables may still be subsetted but will likely need to use the retain glyph ids option and configure the subset to pass through the layout tables untouched.

In other words, subsetting allows you to take a large font and construct a new, smaller font which has only those characters that you need. Be sure to check the license of the font though, as not all fonts can be legally subsetted.

Why?

Many modern fonts can contain hundreds or even thousands of glyphs, of which only a couple dozen or maybe hundred is needed in any single document. This also means that modern fonts can be very bulky compared to what is actually needed. The solution to this is font subsetting: We can construct a font that includes only those glyphs and features that are needed for the document.

Usage

The simplest way to construct a subset of a font is to use subset() function. In the following example, we keep only glyphs that are needed show any combination of characters ‘a’, ‘b’ and ‘c’, e.g. “abc” and “cabba” can be rendered, but “foobar” cannot:

let font = fs::read("tests/fonts/NotoSans.ttf")?;
let subset_font = hb_subset::subset(&font, "abc".chars())?;
fs::write("tests/fonts/subset.ttf", subset_font)?;

To get more control over how the font is subset and what gets included, you can use the lower level API directly:

// Load font directly from a file
let font = Blob::from_file("tests/fonts/NotoSans.ttf")?;
let font = FontFace::new(font)?;

// Construct a subset manually and include only some of the letters
let mut subset = SubsetInput::new()?;
subset.unicode_set().insert('f');
subset.unicode_set().insert('i');

// Subset the font using just-constructed subset input
let new_font = subset.subset_font(&font)?;

// Extract the raw font and write to an output file
std::fs::write("tests/fonts/subset.ttf", &*new_font.underlying_blob())?;

Using bundled version of HarfBuzz

By default, this crate uses the system HarfBuzz installation. If it is not available, or it is too old, this crate can also used a bundled copy of HarfBuzz by using feature bundled:

cargo add hb-subset --features bundled

Modules

  • sys
    Raw FFI bindings to HarfBuzz.

Structs

  • AllocationError
    An error returned when an allocation fails.
  • Blob
    Blobs wrap a chunk of binary data.
  • FlagRef
    Helper which sets the flags on associated SubsetInput on drop.
  • Flags
    Flags for SubsetInput.
  • FontFace
    A font face is an object that represents a single face from within a font family.
  • FontFaceExtractionError
    An error returned when a font face could not be extracted from blob.
  • Language
    Data type for languages.
  • Map
    Map objects are integer-to-integer hash-maps.
  • MapIter
    Iterator over Map key-value pairs.
  • PreprocessedFontFace
    Font face that has been preprocessed for subsetting.
  • Set
    Set objects represent a mathematical set of integer values.
  • SetIter
    Iterator over Set.
  • SubsetInput
    A description of how a font should be subset.
  • SubsetPlan
    Information about how a subsetting operation will be executed.
  • SubsettingError
    An error returned when font face could not be subset.
  • Tag
    Four byte integers, each byte representing a character.

Functions

  • subset
    A convenient method to create a subset of a font over given characters.

Type Aliases